ADA Programming Guide/ADA Programming Guide.iso/ada_gwu/readme.run

Text File | 1996-01-30 | 16KB | 399 lines

    GWMON Parallel Ada Monitor for 386/486 PCs
    Copyright (C) 1993, Charles W. Kann  & Michael Bliss Feldman
                        [e-mail] [e-mail]

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.



1 - INTRODUCTION

    This is an introduction to the GWUMON execution shell.  This shell allows
a user to interact with the NYUAda Run Time System (RTS) while the RTS is
executing the user program.  This interaction with the RTS allows the user
to see the program statement as they are being executed, and to monitor
the CPU as the program runs.

    This README file walks the user through an initial run of the monitor.
Note that there are several Ada programs which are given with this distribution.
One of them, FIRST.ADA, will be used to give a walk through of the system.

1.1 SYSTEM SETUP

1.1.1 IF YOU HAVE NOT PREVIOUSLY INSTALLED NYUAda or GWUAda

    If you have never installed NYUAda or GWAda, then use the following
directions to install the GWUMON system.

    First, make a directory where the programs which will be used by
GWUMON will be stored, and change to that directory.  It is suggested that
the directory "ADAED" be used.  Assuming that this directory will be named
"ADAED" and will be on the "C:" drive, this can be done by typing:

    c:
    cd \
    mkdir adaed
    cd c:\adaed

    The programs which install GWUMON are contained in two self extracting
archives called GWDISK1.EXE and GWDISK2.EXE.  These are selfextracting
archieves.  To load the GWUMON system, simply run the archive executable.
Assuming that the archive is on the "A:" drive, type the following:

    c:
    cd \adaed
    a:\gwdisk1
    a:\gwdisk2

    The GWUMON system should now been installed.  Several system variables
need to be set or changed to run the ADAED system.  A batch program,
MONSETUP.BAT, is included with the distribution.  If you wish, the following
instructions will allow you to use the GWUMON without modifying this file.
Otherwise, this .BAT file will give you instructions on what needs to be
modified in your AUTOEXEC.BAT to allow GWUMON to run.

    If you are not going to modify MONSETUP.BAT, then the following
instructions will allow you to setup your computer to run the monitor.  One
time only, type the following:

    c:
    cd \adaed
    monsetup
    mkdir myprogs
    cd \adaed\myprogs

    Each time you wish to edit or compile and modify a program, always make
sure that you have run monsetup, that you are in the "\adaed\myprogs" directory,
ie:

    c:
    cd \adaed
    monsetup
    cd myprogs

1.1.2 IF YOU ALREADY HAVE INSTALLED NYUAda or GWAda

    If you already have installed NYUAda or GWAda, you probably are familar
with how they work.  GWUMON is simply an additional shell to be used around
ADAEXEC.  Therefore, these instructions will assume that you are familar
with NYUAda.

    First, change to the directory where you have stored NYUAda or GWAda.
Save the files in this directory.  GWUMON will overwrite all the old NYUAda
and GWAda files.  Note that GWUMON uses NYUAda as a baseline, but it does not
work with the unchanged NYUAda programs.  Do not try to run GWUMON with any
NYUAda programs which have not come with the GWUMON distribution.  The
instructions to achieve the above, assuming NYUAda and GWAda are in the
directory /ADAED, are as follows:

    c:
    cd \adaed
    mkdir save
    copy *.* save

    After you have saved the files in your NYUAda directory, unarchive the
files from GWUARC.  Since GWUARC is a self extracting archive, the files can
be retrieve by simply running GWDISK1 and GWDISK2 from the directory where
you wish to place the files, as follows

    c:
    cd \adaed
    a:\gwdisk1
    a:\gwdisk2

    Once you have GWUMON installed, all your NYUAda and GWAda programs
should work as before with only one modification.  Since GWUMON uses a slightly
different AdaEd interpreter, the library files are changed slightly.  You
should therefore remake all your libraries new, and you will have to recompile
and bind all your programs.



2 RUNNING THE MONITOR

2.1 RUNNING FROM THE COMMAND LINE

    Although GWUMON was written to be integrated into GWAda, it can be run
standalone from the command line.  If you wish to do this, you should make
sure that all your compiles include the "-a" option, ie:

    adacomp -a -b first.ada

    When you run GWUMON, the command line options are exactly the same as
the options for "adaexec", so you should check the NYUAda documentation if
you wish to set these options.  Note that if you don't set the "-a" option
in the compile, the monitor will NOT work!


2.2 RUNNING FROM GWUAda

    If you are running GWUMON from GWAda, you do not have to worry about
any compile options, etc.  GWAda sets them for you.  From the command line,
type "GWAda", and the GWAda system will start up.

    To run the monitor from GWAda, go to the options menu, and choose the
option "Run Monitor".  This is a toggle which turns the monitor on and off.
If you choose not to run the monitor, the NYU AdaExec program is run as
usual from GWAda.


2.3 A FIRST RUN OF GWUMON

    This section will give you a step by step walk through on how to use
GWUMON from GWAda.

    1 - Copy the ada program "FIRST.ADA" from the directory \ADAED
        to the directory \ADAED\MYPROGS

    2 - Start GWAda by typing "GWAda FIRST.ADA"

    3 - The GWAda editor should now be running, with the source for
        the program TEST1.ADA in the window.  First, create a new
        library as follows:

        Hit the "ESC" key.
        Type "O" to select the options menu.
        Type "N" to select a new library.

        A New library has been created.

    4 - You should still be on the menu bar.  Type "C" to select
        compile.

    5 - When the compile is done, you will no longer have the menu
        bar.  Type "ESC" to bring up the menu bar, and type "B" to
        bind the program.

    6 - You will be asked for the program to bind.  Select "first".
        The program is now bound.

    7 - Type "O" to select options again.  Use the down arrow key
        to select the option "Run Monitor".  Hit enter to select
        this option.

    8 - Type "R" to run the program.  When asked what program to
        run, select "test1".

    9 - You should now have up the monitor screen.

      10 - Follow the instructions in the FIRST.ADA program preamble.




3 GWUMON OPTIONS

    There are many options which can be set in GWUMON.  The best way to
find out what they all are is to experiment with the system.  There are
several programs distributed with the monitor which will help to give
the user some experience with using the monitor.  It is suggested that the
user try these programs to see how the monitor works.

This section will give an overview of what options are available in GWUMON,
and how they work.  This is given mainly as a reference, and the user should
try these options to see how they work.

3.1 SETUP SCREENS

3.1.1 INITIAL SETUP SCREEN

    When GWUMON begins execution, the Initial Setup screen is brought up.
This screen is only brought up once per run, when GWUMON starts to run.
It has the following three options:

    1 - Execution Speed - This is the initial speed of the program
        when it starts to run.  It is relative to the maximum
        speed of the monitor.  Once the monitor has started
        running, the up/down arrow keys are used to adjust the
        speed of the monitor.

    2 - Exception Tracing - This determines whether or not exceptions
            will be traced when the monitor is running.  If this option
        is set to no, unhandled exceptions are not reported.

    3 - Does your program use tasks - This question determines how the
        monitor runs.  The monitor has two modes, one which is used
        for sequential programs, and one which is used for concurrent
        programs (ie. programs which use tasks).  These two modes are
        incompatable (ie. programs which have tasks should not be
        run in sequential mode, and vice versa).  Since the monitor
        cannot determine before execution if the program uses tasks
        or not, it is up to the user to set this option correctly.

3.1.2 SEQUENTIAL SETUP MENU

    If the user has selected Sequential Execution (ie. no tasks are used),
then the next menu to come up will be the Sequential Setup menu.  This menu
can also be brought up by using the F10 key when the program is running in
sequential mode. This menu has the following options:

    1 - Monitor Window Size - This option selects how large to make the
            monitor window.  If the small window is choosen, the program
            output window is made larger.  If the large window is choosen,
            the program output window is made smaller (just 2 rows).  This
        option should be choosen based on how much of the program
        output should be seen, verses program source code.

    2 - When to Pause Execution - This determines when the monitor
        will pause execution and wait for the users' input to
        allow it to continue.  The options here are:

        As a Program Enters/Exits Procedures - If this option is
        set to "Y", then each time a block is entered or exited, the
        program will pause for user input.

        As Each Line Of Code Is Executed - If this option is set to
        "Y", then each time a line of code is run, the program will
        pause for user input.  Note that a line of code could
        represent more than 1 p-code statement.

3.1.3 TASKING SETUP MENU

    If the user has selected Concurrent Execution (ie. tasks are used),
then the next menu to come up will be the Tasking Setup menu.  This menu
can also be brought up by using the F10 key when the program is running in
tasking mode. This menu has the following options:

    1 - General Information

        1.1 - What do you want to monitor - The user can monitor
        either the lines as they are executed, execution profile
        for the tasks, or nothing.

        1.2 - Type of Delay - This option has not yet been implemented.

        1.3 - Tasking Model - This deals with the type of tasking.
        This can either be "Run Til Blocked" (ie. continue to run
        until the task gives up the CPU) or Round Robin (ie. each
        task runs until it's quantum is used up).

        1.3.1 - If the tasking model choosen is round robin, then
        the size of the quantum must be set.  This is the number of
        p-code statements are executed between a task switch.

    2 - It option 1.1 was choosen to monitor lines, then these options
          are set.

        2.1 - Type of Monitor Window - This determines how many
        tasks can be seen on the screen at a time, and the type of
        windows that display those tasks.

        2.2 - When to Pause Execution - This determines when the
        monitor will pause execution and wait for the users' input
        to allow it to continue.  The options here are:

        As a Program Enters/Exits Procedures - If this option is
        set to "Y", then each time a block is entered or exited, the
        program will pause for user input.

        As Each Line Of Code Is Executed - If this option is set to
        "Y", then each time a line of code is run, the program will
        pause for user input.  Note that a line of code could
        represent more than 1 p-code statement.

    3 - If option 1.1 choose to profile the program, then the number
        of p-code statments which are executed between reports of
        the profile report is set here.




3.2 CONTROL SCREEN

    The Control Screen allows the user to choose which tasks they wish to
    see on the screen when the monitor is running.  It tells the current
    status of the tasks, and allows the user to choose which tasks they
    wish to monitor.  The field WON tells which windows are currently being
    monitored, if the field is "yes", the task is attatched to a monitor
    window.  This WON field can be toggled by using the arrow keys to
    position yourself on the task you want to change, and typing the "t"
    key.

    If there are more then one screens worth of tasks, then hitting the down
    arrrow on the last task on the screen will bring up the next series of
    tasks.

3.3 OPTIONS WHEN LINE MONITOR IS RUNNING

    Line monitoring allows the user to see what lines are being executed
    in each task as they are running.

    Many of the options which are available from the SETUP screen which
    pertain to line monitoring can be set with a single key stroke while the
    monitor is running.  This is to save the user the time of having to
    go into the SETUP screen and change the options.  These commands are
    summarized here:

        Up Arr - doubles the speed of the interpreter (ie. cuts the
         delay in half.)
    Dn Arr - halves the speed of the interpreter (ie. doubles the
         delay.)
    ctrl a - brings up the control screen to allow the user to
         set the tasks they would like to monitor.
        ctrl b - stops the monitor from running.  This options allows the
           user to run their program without any monitor output.  Note
         that the delay still is in effect, and the program can be
         slowed down or sped up.
        ctrl c or ESC - stop the execution of the monitor.
    ctrl d - Brings up the setup screen.
    ctrl h - Brings up the help screen.
        ctrl l - Sets line step mode, where the monitor stops after each
         line that is in a currently active monitor window has been
         executed.
        ctrl t - Sets line task step, where the monitor stops after each
         task switch that is in a currently active monitor window
         has been executed.

3.4 EXECUTION STATUS CODES

    The status codes for line monitoring are as follows:

        R - Wait on Rendezvous      M - Rendezvous Meet
        D - Wait on Delay           * - Task Ready to Run
        --> Task currently running


    Note that all this information can be obtained by typing "CTRL-H" when
    the line monitor is running.


3.5 EXECUTION PERCENTAGE WINDOW

    The executions percent window allows the user to compare the relative
    number of clock cycles each task uses.  The only option on this
    window is to turn the monitoring by using the CTRL-B key.




4.0 KNOWN BUGS AND OTHER HINTS

     There are a number of known bugs and problems which can occur when
     using the monitor.  These will be fixed for the next release.

    1 - Too many key strokes which are not processed can cause the
        monitor to hang.  For example, if you hit alot of DOWN ARROW
        keys to slow the monitor down, the system will take longer to
        process these keys, and eventually will hang.  If this happens,
        the computer must be rebooted.

    2 - The monitor comes up but no source lines are displayed and
        the task line is not advanced.  This can be caused by the
        source program not being compiled with the "-a" option.  If
        you are compiling from the command line, make sure you use
        the "-a" option on the compile.

        Note that this will not happen if the monitor is run from
        GWAda.